Geolocation Validation API

This document outlines the details of the Geocoding API.

API Description

Objective

The geo-location validation API verifies if the distance between a customer's address in textual format and their location coordinates captured in an application is within the configured range of distance.

Input	Output
The customer's address and location coordinates.	The boolean result of the distance verification between the two inputs and the details of the distance.

API URL

https://ind-engine.thomas.hyperverge.co/v1/geoLocationValidation

https://ind-engine.thomas.hyperverge.co/v1/geoLocationValidation

API Endpoint

geoLocationValidation

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Valid Values
content-type	Mandatory	This parameter defines the media type for the request payload.	application/json
appId	Mandatory	Application ID shared by HyperVerge	N/A. This is a unique value.
appKey	Mandatory	Application Key shared by HyperVerge	N/A. This is a unique value.
transactionId	Mandatory	Unique ID for the customer journey.	N/A. Any defined unique value mapped to a transaction in your business ecosystem.

Inputs

The following table provides information on the parameters used in the request body of the Geo-location Validation API .

Parameter	Mandatory or Optional	Description
latitude	Mandatory	Latitude in the captured location coordinates
longitude	Mandatory	Longitude in the captured location coordinates.
address	Mandatory	Address of the user in text format.

Request

The following code shows a standard curl request for the API.

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/geoLocationValidation' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "latitude": "<Enter_the_latitude_coordinates>",
    "longitude": "<Enter_the_longitude_coordinates>",
    "address": "<Enter_the_valid_address>"
}'

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/geoLocationValidation' \ --header 'Content-Type: application/json' \ --header 'appId: <Enter_the_HyperVerge_appId>' \ --header 'appKey: <Enter_the_HyperVerge_appKey>' \ --header 'transactionId: <Enter_the_HyperVerge_transactionID>' \ --data '{ "latitude": "<Enter_the_latitude_coordinates>", "longitude": "<Enter_the_longitude_coordinates>", "address": "<Enter_the_valid_address>" }'

Success Response

The following is a response for a valid request made to the API:

{
  "statusCode": "200",
  "distance": 8539795.18642073,
  "locationMatch": false,
  "addressInformation": {
    "results": [
      {
        "address_components": [...]
      }
    ]
  }
}

{ "statusCode": "200", "distance": 8539795.18642073, "locationMatch": false, "addressInformation": { "results": [ { "address_components": [...] } ] } }

Success Response Details

The following table provides the details of the fields in a success response.

Field	Description
distance	The field returns the distance between the address and location coordinates in metres.
locationMatch	By default, this field returns a "true" value if the distance is less than 1000m. The field value is a configurable based on your requirement.
address_components	The field provides additional information on the entered address.
types	The types[] array indicates the type of the returned result. This array contains a set of zero or more tags identifying the type of feature returned in the result. For example, a geocode of "Chicago" returns "locality" which indicates that "Chicago" is a city, and also returns "political" which indicates it is a political entity. Components might have an empty types array when there are no known types for that address component.
formatted_address	This is a string containing the human-readable address of this location.
address_components	This is an array containing the separate components applicable to this address. Each address component typically contains the following fields: types[] is an array indicating the type of the address component long_name is the full text description or name of the address component as returned by the Geocoder. short_name is an abbreviated textual name for the address component, if available. For example, an address component for the state of Alaska may have a long_name of "Alaska" and a short_name of "AK" using the 2-letter postal abbreviation.
postcode_localities[]	It is an array denoting all the localities contained in a postal code. This is only present when the result is a postal code that contains multiple localities.
geometry	This field contains the following information: locationcontains the geocoded latitude, longitude value. For normal address lookups, this field is typically the most important. location_type stores additional data about the specified location. The following values are currently supported: ROOFTOP indicates that the returned result is a precise geocode for which we have location information accurate down to street address precision. RANGE_INTERPOLATED indicates that the returned result reflects an approximation (usually on a road) interpolated between two precise points (such as intersections). Interpolated results are generally returned when rooftop geocodes are unavailable for a street address. GEOMETRIC_CENTER indicates that the returned result is the geometric center of a result such as a polyline (for example, a street) or polygon (region). APPROXIMATE indicates that the returned result is approximate. short_name is an abbreviated textual name for the address component, if available. For example, an address component for the state of Alaska may have a long_name of "Alaska" and a short_name of "AK" using the 2-letter postal abbreviation. viewport contains the recommended viewport for displaying the returned result, specified as two latitude,longitude values defining the southwest and northeast corner of the viewport bounding box. Generally the viewport is used to frame a result when displaying it to a user. bounds (optionally returned) stores the bounding box which can fully contain the returned result. Note that these bounds may not match the recommended viewport.
partial_match	The geocoder did not return an exact match for the original request, though it was able to match part of the requested address. You may wish to examine the original request for misspellings and/or an incomplete address.

Failure Response

The following code snippet shows a failure response from the API:

{
  "statusCode": "200",
  "distance": null,
  "locationMatch": false,
  "addressInformation": {
    "results": [],
    "status": "ZERO_RESULTS"
  }
}

{ "statusCode": "200", "distance": null, "locationMatch": false, "addressInformation": { "results": [], "status": "ZERO_RESULTS" } }

Error Responses

The following code snippets show the error responses from the API.

Credentials Error

{
  "message": "Missing/Invalid credentials",
  "statusCode": 401,
  "status": "failure"
}

{ "message": "Missing/Invalid credentials", "statusCode": 401, "status": "failure" }

Server Error

{
  "message": "Internal Server Error",
  "statusCode": 500,
  "status": "failure"
}

{ "message": "Internal Server Error", "statusCode": 500, "status": "failure" }

Latitude Error

{
"message": "Input Validation Error: requires property \"latitude\"", 
"statusCode": 400,
"status": "failure"
}

{ "message": "Input Validation Error: requires property \"latitude\"", "statusCode": 400, "status": "failure" }

Longitude Error

{
"message": "Input Validation Error: requires property \"longitude\"",
"statusCode": 400,
"status": "failure"
}

{ "message": "Input Validation Error: requires property \"longitude\"", "statusCode": 400, "status": "failure" }

Address Error

{
"message": "Input Validation Error: requires property \"address\"",
"statusCode": 400,
"status": "failure"
}

{ "message": "Input Validation Error: requires property \"address\"", "statusCode": 400, "status": "failure" }

##s# Error Response Details

Error Message	Error Description
OVER_DAILY_LIMIT	It indicates any one of the following: The API key is missing or invalid. Billing has not been enabled on your account. A self-imposed usage cap has been exceeded. The provided method of payment is no longer valid (for example, a credit card has expired).
OVER_QUERY_LIMIT	You are over your quota.
REQUEST_DENIED	The request was denied.
INVALID_REQUEST	It generally indicates one of the following scenarios: The query (address, components or latlng) is missing. The API received an invalid result_type or location_type.
UNKNOWN_ERROR	The request could not be processed due to a server error. It may succeed if you try again.